package suncertify.gui;

import javax.swing.JTable;

import suncertify.application.ApplicationMode;
import suncertify.contractors.exceptions.CloseContractorsException;
import suncertify.contractors.exceptions.ContractorFindException;
import suncertify.contractors.exceptions.ContractorUpdateException;
import suncertify.contractors.exceptions.ReadAllContractorsException;

/**
 * This interface defines the relationship and dependency between the {@link ClientApplicationFrame} (which represents
 * the view in a MVC pattern) and the controller of a MVC pattern. The implementor of the this interface represents the
 * controller for the {@link ClientApplicationFrame} JFrame.
 * 
 * <p>
 * The {@link ClientApplicationFrame} class is responsible for building the GUI, the actions that are triggered by the
 * GUI (e.g. search contractors and contractor booking) are handled by the implementor of this interface.
 * 
 * <p>
 * The main objective of this interface is to decouple the {@link ClientApplicationFrame} from its controller type and
 * it allows implementing other controllers without changing the {@link ClientApplicationFrame} class.
 * 
 * @see ClientApplicationFrameController
 * @see ClientApplicationFrame
 * 
 */
public interface ClientApplicationFrameControllerInterface {

    /**
     * Definition for a method that sets the view in the implementor of this interface. The view type is
     * <code>Object</code> to make the interface more generic. The controller must validate the type of the object and
     * make sure it is the supported type e.g. the {@link ClientApplicationFrameController} implementation expects the
     * <code>contractorsTable</code> parameter to be of type {@link JTable}.
     * 
     * @param contractorsTable
     *            Reference to the control that represents the view of the controller e.g. a reference to a
     *            {@link JTable} instance.
     */
    public void setViewControl(Object contractorsTable);

    /**
     * Definition for a method that shows all contractors in the view provided by {@link #setViewControl(Object)}.
     * 
     * @throws ReadAllContractorsException
     *             Thrown if an error occurs while retrieving the contractors.
     * @throws Exception
     *             If any unexpected errors occur.
     */
    public void getAllContractors() throws ReadAllContractorsException, Exception;

    /**
     * Definition for a method that searches the database for all contractors that match a specific name and/or location
     * and updates the view provided by the {@link #setViewControl(Object)} accordingly.
     * 
     * @param name
     *            The search name value.
     * @param location
     *            The search location value.
     * @throws ContractorFindException
     *             Thrown if an error occurs while executing the search.
     * @throws Exception
     *             Thrown if any unexpected error occurs.
     */
    public void searchNameLocationContractors(String name, String location) throws ContractorFindException, Exception;

    /**
     * Definition for a method that changes the owner value of a specific contractor and updates the view provided by
     * {@link #setViewControl(Object)} accordingly.
     * 
     * @param parentWindow
     *            The parent window to which the book dialog is shown as a modal dialog. The book dialog allows entering
     *            the owner value for the contractor or clearing the owner value of the contractor.
     * @throws ContractorUpdateException
     *             Should be thrown if the contractor update fails.
     * @throws Exception
     *             Should be thrown if any other error occurs.
     */
    public void bookContractor(Object parentWindow) throws ContractorUpdateException, Exception;

    /**
     * Definition for a method that removes the owner value of a specific contractor and updates the view provided by
     * {@link #setViewControl(Object)} accordingly.
     * 
     * @throws ContractorUpdateException
     *             Should be thrown if the contractor update fails.
     * @throws Exception
     *             Should be thrown if any other error occurs.
     */
    public void unbookContractor() throws ContractorUpdateException, Exception;

    /**
     * Definition for a method that closes the applications database file.
     * 
     * @throws CloseContractorsException
     *             Should be thrown if the close operation fails.
     * @throws Exception
     *             Should be thrown if any other error occurs.
     */
    public void closeDatabaseFile() throws CloseContractorsException, Exception;

    /**
     * Definition for a method that terminates the application.
     */
    public void terminateApplication();

    /**
     * Definition for a method that returns the application's mdoe.
     * 
     * @return the applicatgion's mode.
     */
    public ApplicationMode getApplicationMode();
}